home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / include / fuse / fuse.h < prev   
Encoding:
C/C++ Source or Header  |  2006-05-11  |  18.4 KB  |  584 lines
  1. /*
  2.     FUSE: Filesystem in Userspace
  3.     Copyright (C) 2001-2006  Miklos Szeredi <miklos@szeredi.hu>
  4.  
  5.     This program can be distributed under the terms of the GNU LGPL.
  6.     See the file COPYING.LIB.
  7. */
  8.  
  9. #ifndef _FUSE_H_
  10. #define _FUSE_H_
  11.  
  12. /* This file defines the library interface of FUSE */
  13.  
  14. /* IMPORTANT: you should define FUSE_USE_VERSION before including this
  15.    header.  To use the newest API define it to 26 (recommended for any
  16.    new application), to use the old API define it to 21 (default) 22
  17.    or 25, to use the even older 1.X API define it to 11. */
  18.  
  19. #ifndef FUSE_USE_VERSION
  20. #define FUSE_USE_VERSION 21
  21. #endif
  22.  
  23. #include "fuse_common.h"
  24.  
  25. #include <sys/types.h>
  26. #include <sys/stat.h>
  27. #include <sys/statvfs.h>
  28. #include <utime.h>
  29.  
  30. #ifdef __cplusplus
  31. extern "C" {
  32. #endif
  33.  
  34. /* ----------------------------------------------------------- *
  35.  * Basic FUSE API                                              *
  36.  * ----------------------------------------------------------- */
  37.  
  38. /** Handle for a FUSE filesystem */
  39. struct fuse;
  40.  
  41. /** Structure containing a raw command */
  42. struct fuse_cmd;
  43.  
  44. /** Function to add an entry in a readdir() operation
  45.  *
  46.  * @param buf the buffer passed to the readdir() operation
  47.  * @param name the file name of the directory entry
  48.  * @param stat file attributes, can be NULL
  49.  * @param off offset of the next entry or zero
  50.  * @return 1 if buffer is full, zero otherwise
  51.  */
  52. typedef int (*fuse_fill_dir_t) (void *buf, const char *name,
  53.                                 const struct stat *stbuf, off_t off);
  54.  
  55. /* Used by deprecated getdir() method */
  56. typedef struct fuse_dirhandle *fuse_dirh_t;
  57. typedef int (*fuse_dirfil_t) (fuse_dirh_t h, const char *name, int type,
  58.                               ino_t ino);
  59.  
  60. /**
  61.  * The file system operations:
  62.  *
  63.  * Most of these should work very similarly to the well known UNIX
  64.  * file system operations.  A major exception is that instead of
  65.  * returning an error in 'errno', the operation should return the
  66.  * negated error value (-errno) directly.
  67.  *
  68.  * All methods are optional, but some are essential for a useful
  69.  * filesystem (e.g. getattr).  Open, flush, release, fsync, opendir,
  70.  * releasedir, fsyncdir, access, create, ftruncate, fgetattr, init and
  71.  * destroy are special purpose methods, without which a full featured
  72.  * filesystem can still be implemented.
  73.  */
  74. struct fuse_operations {
  75.     /** Get file attributes.
  76.      *
  77.      * Similar to stat().  The 'st_dev' and 'st_blksize' fields are
  78.      * ignored.  The 'st_ino' field is ignored except if the 'use_ino'
  79.      * mount option is given.
  80.      */
  81.     int (*getattr) (const char *, struct stat *);
  82.  
  83.     /** Read the target of a symbolic link
  84.      *
  85.      * The buffer should be filled with a null terminated string.  The
  86.      * buffer size argument includes the space for the terminating
  87.      * null character.  If the linkname is too long to fit in the
  88.      * buffer, it should be truncated.  The return value should be 0
  89.      * for success.
  90.      */
  91.     int (*readlink) (const char *, char *, size_t);
  92.  
  93.     /* Deprecated, use readdir() instead */
  94.     int (*getdir) (const char *, fuse_dirh_t, fuse_dirfil_t);
  95.  
  96.     /** Create a file node
  97.      *
  98.      * There is no create() operation, mknod() will be called for
  99.      * creation of all non-directory, non-symlink nodes.
  100.      */
  101.     int (*mknod) (const char *, mode_t, dev_t);
  102.  
  103.     /** Create a directory */
  104.     int (*mkdir) (const char *, mode_t);
  105.  
  106.     /** Remove a file */
  107.     int (*unlink) (const char *);
  108.  
  109.     /** Remove a directory */
  110.     int (*rmdir) (const char *);
  111.  
  112.     /** Create a symbolic link */
  113.     int (*symlink) (const char *, const char *);
  114.  
  115.     /** Rename a file */
  116.     int (*rename) (const char *, const char *);
  117.  
  118.     /** Create a hard link to a file */
  119.     int (*link) (const char *, const char *);
  120.  
  121.     /** Change the permission bits of a file */
  122.     int (*chmod) (const char *, mode_t);
  123.  
  124.     /** Change the owner and group of a file */
  125.     int (*chown) (const char *, uid_t, gid_t);
  126.  
  127.     /** Change the size of a file */
  128.     int (*truncate) (const char *, off_t);
  129.  
  130.     /** Change the access and/or modification times of a file */
  131.     int (*utime) (const char *, struct utimbuf *);
  132.  
  133.     /** File open operation
  134.      *
  135.      * No creation, or truncation flags (O_CREAT, O_EXCL, O_TRUNC)
  136.      * will be passed to open().  Open should check if the operation
  137.      * is permitted for the given flags.  Optionally open may also
  138.      * return an arbitrary filehandle in the fuse_file_info structure,
  139.      * which will be passed to all file operations.
  140.      *
  141.      * Changed in version 2.2
  142.      */
  143.     int (*open) (const char *, struct fuse_file_info *);
  144.  
  145.     /** Read data from an open file
  146.      *
  147.      * Read should return exactly the number of bytes requested except
  148.      * on EOF or error, otherwise the rest of the data will be
  149.      * substituted with zeroes.  An exception to this is when the
  150.      * 'direct_io' mount option is specified, in which case the return
  151.      * value of the read system call will reflect the return value of
  152.      * this operation.
  153.      *
  154.      * Changed in version 2.2
  155.      */
  156.     int (*read) (const char *, char *, size_t, off_t, struct fuse_file_info *);
  157.  
  158.     /** Write data to an open file
  159.      *
  160.      * Write should return exactly the number of bytes requested
  161.      * except on error.  An exception to this is when the 'direct_io'
  162.      * mount option is specified (see read operation).
  163.      *
  164.      * Changed in version 2.2
  165.      */
  166.     int (*write) (const char *, const char *, size_t, off_t,
  167.                   struct fuse_file_info *);
  168.  
  169.     /** Just a placeholder, don't set */
  170.     /** Get file system statistics
  171.      *
  172.      * The 'f_frsize', 'f_favail', 'f_fsid' and 'f_flag' fields are ignored
  173.      *
  174.      * Replaced 'struct statfs' parameter with 'struct statvfs' in
  175.      * version 2.5
  176.      */
  177.     int (*statfs) (const char *, struct statvfs *);
  178.  
  179.     /** Possibly flush cached data
  180.      *
  181.      * BIG NOTE: This is not equivalent to fsync().  It's not a
  182.      * request to sync dirty data.
  183.      *
  184.      * Flush is called on each close() of a file descriptor.  So if a
  185.      * filesystem wants to return write errors in close() and the file
  186.      * has cached dirty data, this is a good place to write back data
  187.      * and return any errors.  Since many applications ignore close()
  188.      * errors this is not always useful.
  189.      *
  190.      * NOTE: The flush() method may be called more than once for each
  191.      * open().  This happens if more than one file descriptor refers
  192.      * to an opened file due to dup(), dup2() or fork() calls.  It is
  193.      * not possible to determine if a flush is final, so each flush
  194.      * should be treated equally.  Multiple write-flush sequences are
  195.      * relatively rare, so this shouldn't be a problem.
  196.      *
  197.      * Filesystems shouldn't assume that flush will always be called
  198.      * after some writes, or that if will be called at all.
  199.      *
  200.      * Changed in version 2.2
  201.      */
  202.     int (*flush) (const char *, struct fuse_file_info *);
  203.  
  204.     /** Release an open file
  205.      *
  206.      * Release is called when there are no more references to an open
  207.      * file: all file descriptors are closed and all memory mappings
  208.      * are unmapped.
  209.      *
  210.      * For every open() call there will be exactly one release() call
  211.      * with the same flags and file descriptor.  It is possible to
  212.      * have a file opened more than once, in which case only the last
  213.      * release will mean, that no more reads/writes will happen on the
  214.      * file.  The return value of release is ignored.
  215.      *
  216.      * Changed in version 2.2
  217.      */
  218.     int (*release) (const char *, struct fuse_file_info *);
  219.  
  220.     /** Synchronize file contents
  221.      *
  222.      * If the datasync parameter is non-zero, then only the user data
  223.      * should be flushed, not the meta data.
  224.      *
  225.      * Changed in version 2.2
  226.      */
  227.     int (*fsync) (const char *, int, struct fuse_file_info *);
  228.  
  229.     /** Set extended attributes */
  230.     int (*setxattr) (const char *, const char *, const char *, size_t, int);
  231.  
  232.     /** Get extended attributes */
  233.     int (*getxattr) (const char *, const char *, char *, size_t);
  234.  
  235.     /** List extended attributes */
  236.     int (*listxattr) (const char *, char *, size_t);
  237.  
  238.     /** Remove extended attributes */
  239.     int (*removexattr) (const char *, const char *);
  240.  
  241.     /** Open directory
  242.      *
  243.      * This method should check if the open operation is permitted for
  244.      * this  directory
  245.      *
  246.      * Introduced in version 2.3
  247.      */
  248.     int (*opendir) (const char *, struct fuse_file_info *);
  249.  
  250.     /** Read directory
  251.      *
  252.      * This supersedes the old getdir() interface.  New applications
  253.      * should use this.
  254.      *
  255.      * The filesystem may choose between two modes of operation:
  256.      *
  257.      * 1) The readdir implementation ignores the offset parameter, and
  258.      * passes zero to the filler function's offset.  The filler
  259.      * function will not return '1' (unless an error happens), so the
  260.      * whole directory is read in a single readdir operation.  This
  261.      * works just like the old getdir() method.
  262.      *
  263.      * 2) The readdir implementation keeps track of the offsets of the
  264.      * directory entries.  It uses the offset parameter and always
  265.      * passes non-zero offset to the filler function.  When the buffer
  266.      * is full (or an error happens) the filler function will return
  267.      * '1'.
  268.      *
  269.      * Introduced in version 2.3
  270.      */
  271.     int (*readdir) (const char *, void *, fuse_fill_dir_t, off_t,
  272.                     struct fuse_file_info *);
  273.  
  274.     /** Release directory
  275.      *
  276.      * Introduced in version 2.3
  277.      */
  278.     int (*releasedir) (const char *, struct fuse_file_info *);
  279.  
  280.     /** Synchronize directory contents
  281.      *
  282.      * If the datasync parameter is non-zero, then only the user data
  283.      * should be flushed, not the meta data
  284.      *
  285.      * Introduced in version 2.3
  286.      */
  287.     int (*fsyncdir) (const char *, int, struct fuse_file_info *);
  288.  
  289.     /**
  290.      * Initialize filesystem
  291.      *
  292.      * The return value will passed in the private_data field of
  293.      * fuse_context to all file operations and as a parameter to the
  294.      * destroy() method.
  295.      *
  296.      * Introduced in version 2.3
  297.      */
  298.     void *(*init) (struct fuse_conn_info *conn);
  299.  
  300.     /**
  301.      * Clean up filesystem
  302.      *
  303.      * Called on filesystem exit.
  304.      *
  305.      * Introduced in version 2.3
  306.      */
  307.     void (*destroy) (void *);
  308.  
  309.     /**
  310.      * Check file access permissions
  311.      *
  312.      * This will be called for the access() system call.  If the
  313.      * 'default_permissions' mount option is given, this method is not
  314.      * called.
  315.      *
  316.      * This method is not called under Linux kernel versions 2.4.x
  317.      *
  318.      * Introduced in version 2.5
  319.      */
  320.     int (*access) (const char *, int);
  321.  
  322.     /**
  323.      * Create and open a file
  324.      *
  325.      * If the file does not exist, first create it with the specified
  326.      * mode, and then open it.
  327.      *
  328.      * If this method is not implemented or under Linux kernel
  329.      * versions earlier than 2.6.15, the mknod() and open() methods
  330.      * will be called instead.
  331.      *
  332.      * Introduced in version 2.5
  333.      */
  334.     int (*create) (const char *, mode_t, struct fuse_file_info *);
  335.  
  336.     /**
  337.      * Change the size of an open file
  338.      *
  339.      * This method is called instead of the truncate() method if the
  340.      * truncation was invoked from an ftruncate() system call.
  341.      *
  342.      * If this method is not implemented or under Linux kernel
  343.      * versions earlier than 2.6.15, the truncate() method will be
  344.      * called instead.
  345.      *
  346.      * Introduced in version 2.5
  347.      */
  348.     int (*ftruncate) (const char *, off_t, struct fuse_file_info *);
  349.  
  350.     /**
  351.      * Get attributes from an open file
  352.      *
  353.      * This method is called instead of the getattr() method if the
  354.      * file information is available.
  355.      *
  356.      * Currently this is only called after the create() method if that
  357.      * is implemented (see above).  Later it may be called for
  358.      * invocations of fstat() too.
  359.      *
  360.      * Introduced in version 2.5
  361.      */
  362.     int (*fgetattr) (const char *, struct stat *, struct fuse_file_info *);
  363. };
  364.  
  365. /** Extra context that may be needed by some filesystems
  366.  *
  367.  * The uid, gid and pid fields are not filled in case of a writepage
  368.  * operation.
  369.  */
  370. struct fuse_context {
  371.     /** Pointer to the fuse object */
  372.     struct fuse *fuse;
  373.  
  374.     /** User ID of the calling process */
  375.     uid_t uid;
  376.  
  377.     /** Group ID of the calling process */
  378.     gid_t gid;
  379.  
  380.     /** Thread ID of the calling process */
  381.     pid_t pid;
  382.  
  383.     /** Private filesystem data */
  384.     void *private_data;
  385. };
  386.  
  387. /*
  388.  * Main function of FUSE.
  389.  *
  390.  * This is for the lazy.  This is all that has to be called from the
  391.  * main() function.
  392.  *
  393.  * This function does the following:
  394.  *   - parses command line options (-d -s and -h)
  395.  *   - passes relevant mount options to the fuse_mount()
  396.  *   - installs signal handlers for INT, HUP, TERM and PIPE
  397.  *   - registers an exit handler to unmount the filesystem on program exit
  398.  *   - creates a fuse handle
  399.  *   - registers the operations
  400.  *   - calls either the single-threaded or the multi-threaded event loop
  401.  *
  402.  * Note: this is currently implemented as a macro.
  403.  *
  404.  * @param argc the argument counter passed to the main() function
  405.  * @param argv the argument vector passed to the main() function
  406.  * @param op the file system operation
  407.  * @return 0 on success, nonzero on failure
  408.  */
  409. /*
  410. int fuse_main(int argc, char *argv[], const struct fuse_operations *op);
  411. */
  412. #define fuse_main(argc, argv, op) \
  413.             fuse_main_real(argc, argv, op, sizeof(*(op)))
  414.  
  415. /* ----------------------------------------------------------- *
  416.  * More detailed API                                           *
  417.  * ----------------------------------------------------------- */
  418.  
  419. /**
  420.  * Create a new FUSE filesystem.
  421.  *
  422.  * @param fd the control file descriptor
  423.  * @param args argument vector
  424.  * @param op the operations
  425.  * @param op_size the size of the fuse_operations structure
  426.  * @return the created FUSE handle
  427.  */
  428. struct fuse *fuse_new(int fd, struct fuse_args *args,
  429.                       const struct fuse_operations *op, size_t op_size);
  430.  
  431. /**
  432.  * Destroy the FUSE handle.
  433.  *
  434.  * The filesystem is not unmounted.
  435.  *
  436.  * @param f the FUSE handle
  437.  */
  438. void fuse_destroy(struct fuse *f);
  439.  
  440. /**
  441.  * FUSE event loop.
  442.  *
  443.  * Requests from the kernel are processed, and the appropriate
  444.  * operations are called.
  445.  *
  446.  * @param f the FUSE handle
  447.  * @return 0 if no error occurred, -1 otherwise
  448.  */
  449. int fuse_loop(struct fuse *f);
  450.  
  451. /**
  452.  * Exit from event loop
  453.  *
  454.  * @param f the FUSE handle
  455.  */
  456. void fuse_exit(struct fuse *f);
  457.  
  458. /**
  459.  * FUSE event loop with multiple threads
  460.  *
  461.  * Requests from the kernel are processed, and the appropriate
  462.  * operations are called.  Request are processed in parallel by
  463.  * distributing them between multiple threads.
  464.  *
  465.  * Calling this function requires the pthreads library to be linked to
  466.  * the application.
  467.  *
  468.  * @param f the FUSE handle
  469.  * @return 0 if no error occurred, -1 otherwise
  470.  */
  471. int fuse_loop_mt(struct fuse *f);
  472.  
  473. /**
  474.  * Get the current context
  475.  *
  476.  * The context is only valid for the duration of a filesystem
  477.  * operation, and thus must not be stored and used later.
  478.  *
  479.  * @param f the FUSE handle
  480.  * @return the context
  481.  */
  482. struct fuse_context *fuse_get_context(void);
  483.  
  484. /**
  485.  * Obsolete, doesn't do anything
  486.  *
  487.  * @return -EINVAL
  488.  */
  489. int fuse_invalidate(struct fuse *f, const char *path);
  490.  
  491. /* Deprecated, don't use */
  492. int fuse_is_lib_option(const char *opt);
  493.  
  494. /**
  495.  * The real main function
  496.  *
  497.  * Do not call this directly, use fuse_main()
  498.  */
  499. int fuse_main_real(int argc, char *argv[], const struct fuse_operations *op,
  500.                    size_t op_size);
  501.  
  502. /* ----------------------------------------------------------- *
  503.  * Advanced API for event handling, don't worry about this...  *
  504.  * ----------------------------------------------------------- */
  505.  
  506. /** Function type used to process commands */
  507. typedef void (*fuse_processor_t)(struct fuse *, struct fuse_cmd *, void *);
  508.  
  509. /** This is the part of fuse_main() before the event loop */
  510. struct fuse *fuse_setup(int argc, char *argv[],
  511.                         const struct fuse_operations *op, size_t op_size,
  512.                         char **mountpoint, int *multithreaded, int *fd);
  513.  
  514. /** This is the part of fuse_main() after the event loop */
  515. void fuse_teardown(struct fuse *fuse, int fd, char *mountpoint);
  516.  
  517. /** Read a single command.  If none are read, return NULL */
  518. struct fuse_cmd *fuse_read_cmd(struct fuse *f);
  519.  
  520. /** Process a single command */
  521. void fuse_process_cmd(struct fuse *f, struct fuse_cmd *cmd);
  522.  
  523. /** Multi threaded event loop, which calls the custom command
  524.     processor function */
  525. int fuse_loop_mt_proc(struct fuse *f, fuse_processor_t proc, void *data);
  526.  
  527. /** Return the exited flag, which indicates if fuse_exit() has been
  528.     called */
  529. int fuse_exited(struct fuse *f);
  530.  
  531. /** Set function which can be used to get the current context */
  532. void fuse_set_getcontext_func(struct fuse_context *(*func)(void));
  533.  
  534. /* ----------------------------------------------------------- *
  535.  * Compatibility stuff                                         *
  536.  * ----------------------------------------------------------- */
  537.  
  538. #if FUSE_USE_VERSION < 26
  539. #  include "fuse_compat.h"
  540. #  undef fuse_main
  541. #  if FUSE_USE_VERSION == 25
  542. #    define fuse_main(argc, argv, op) \
  543.             fuse_main_real_compat25(argc, argv, op, sizeof(*(op)))
  544. #    define fuse_new fuse_new_compat25
  545. #    define fuse_setup fuse_setup_compat25
  546. #    define fuse_operations fuse_operations_compat25
  547. #  elif FUSE_USE_VERSION == 22
  548. #    define fuse_main(argc, argv, op) \
  549.             fuse_main_real_compat22(argc, argv, op, sizeof(*(op)))
  550. #    define fuse_new fuse_new_compat22
  551. #    define fuse_setup fuse_setup_compat22
  552. #    define fuse_operations fuse_operations_compat22
  553. #    define fuse_file_info fuse_file_info_compat22
  554. #  elif FUSE_USE_VERSION == 24
  555. #    error Compatibility with high-level API version 24 not supported
  556. #  else
  557. #    define fuse_dirfil_t fuse_dirfil_t_compat
  558. #    define __fuse_read_cmd fuse_read_cmd
  559. #    define __fuse_process_cmd fuse_process_cmd
  560. #    define __fuse_loop_mt fuse_loop_mt_proc
  561. #    if FUSE_USE_VERSION == 21
  562. #      define fuse_operations fuse_operations_compat2
  563. #      define fuse_main fuse_main_compat2
  564. #      define fuse_new fuse_new_compat2
  565. #      define __fuse_setup fuse_setup_compat2
  566. #      define __fuse_teardown fuse_teardown
  567. #      define __fuse_exited fuse_exited
  568. #      define __fuse_set_getcontext_func fuse_set_getcontext_func
  569. #    else
  570. #      define fuse_statfs fuse_statfs_compat1
  571. #      define fuse_operations fuse_operations_compat1
  572. #      define fuse_main fuse_main_compat1
  573. #      define fuse_new fuse_new_compat1
  574. #      define FUSE_DEBUG FUSE_DEBUG_COMPAT1
  575. #    endif
  576. #  endif
  577. #endif
  578.  
  579. #ifdef __cplusplus
  580. }
  581. #endif
  582.  
  583. #endif /* _FUSE_H_ */
  584.